README for cutnpaste subtree.
(this is a bastardized ascii-version file of the CutPaste.show
showcase file that lives in this same directory)
==============================================================+
This is a draft paper introducing cut and paste for SGI using the
Motif clipboard and ICCCM selection mechanism. The technology
is still under development and we are looking forward to your
feedback on how this strategy fits into your application.
==============================================================+
=================================
Intro - general info
=================================
Cut and paste is a user interface model that allows applications
to communicate data.
In current desktop implementations, most notably the Macintosh,
Windows 3.0, and Motif interfaces, data is transferred within
and across applications using an implicit "Clipboard" model.
The user interface to this Clipboard is presented by three items
in a pull-down Edit menu: "Cut", "Copy", and "Paste". After
data has been selected within an application, the user can then
"transfer" this data to the Clipboard by choosing Cut or Copy.
Cut is used to "move" the selected data to the Clipboard,
removing it from the place it was originally selected within
the application. Copy is used to "copy" the selected data to
the Clipboard, leaving the original selection intact within the
application. At any point after a Cut or Copy into the Clipboard
has been performed, the user may "transfer" the data held in
the Clipboard back into the application by choosing Paste. Note
that the user may perform the Cut/Copy and subsequent Paste either
within the same application , or across any two different
applications which may be run on the system.
Notice that the Clipboard model is really a conceptual model,
which must be presented cleanly and clearly to the user, to allow
them to focus on their challenging job at hand, without
distracting them with the busywork details of operating their
computer. An important part of this conceptual model is the
"correct" conversion of selected data as it is transferred from
one application context to another. Note that the actual
implementation details of how this Clipboard and data transfer
model is coded internally may differ from the simplistic copying
model presented to the user. However, the success of this style
of user interface depends upon the quality of its seamlessness
and simplicity from the user's point of view.
Within the X Windows community, another user interface has
gained widespread popularity for performing "quick transfers" of
text data from one window to another. This mouse-based
shorthand allows text to be selected with the Left Mouse Button,
and supports the quick copy of that selection into the window
where the Middle Mouse Button is clicked. Motif has incorporated
this shorthand, Clipboard-free notion of "Primary Selection" and
"Primary Transfer" alongside the more formal Clipboard model
introduced above. This shorthand model is more appropriate for
experienced users, where the selected data is to be transferred
immediately, and a Clipboard is not needed to preserve the data
across intermediate selections, operations, or the comings and
goings of various application windows.
SGI has adopted the data transfer strategy outlined in the the
OSF/Motif Style Guidelines document (section 3.2, "Selection
Actions"). Motif 1.2 implements the user model described in
that section, supporting both the shortcut style of Primary
Selection-based transfers, as well as the more explicit
Clipboard-based transfers. This dual approach allows
Motif-compliant applications to operate compatibly with a large
base of existing X programs which expect selection-based
transfers, and also to operate compatibly with the growing base
of serious commercial end-user-oriented applications, which
depend on an explicit Clipboard-based transfer model for ease
of use. SGI is fostering this same approach for all programs
developed to run in its end-user environment, to confer these
same interoperability advantages to the users of all applications
found on the SGI platforms. This approach is also in keeping
the Motif's acceptance by the ACE consortium.
Motif text widgets implement the X selection mechanisms using the
mouse to transfer the data through the XA_PRIMARY selection, the
application programmer doesn't need to add any code to do this.
The Motif 1.2 clipboard mechanism, an implementation which is
ICCCM compliant, also provides the programmer with an easy
interface for transferring data through an Edit menu. This
mechanism supports the Clipboard model described above,
transferring data between applications via a 'system' clipboard.
However, the application has the choice to either prestore the
data on the clipboard or to retain the data until such time as it
is actually requested by a Paste operation. This approach
supports a more optimized method for avoiding excessive and
gratuitous copies of what may be massive data sets. In addition,
Motif is compatible with existing X applications that have coded
cut and paste using the X selection mechanism with the
XA_CLIPBOARD selection.
The Motif clipboard conceptually works like this: a user
sketches out an area of interest and goes to the edit menu and
chooses Copy. The application then identifies the data selected,
decides how many ways it can represent the data and then posts
the data in those formats to the Motif clipboard - or posts a
reference to the data format to say that it's available. The
user then chooses Paste from some application edit menu. The
requesting application then may inquire what formats the data
is available in, choose the format that is most suitable for it,
and then begin retrieving the data from the clipboard. In the
event that the application that last placed data on the Motif
clipboard exits or dies, if the data was placed in the Motif
clipboard, the data will persist. If the data was posted to the
clipboard by reference, when the application exits, it can
choose whether or not to leave the data on the clipboard.
The greatest benefit of using the Motif clipboard or the X
selection model is that they permit communication among clients
on different operating systems, file systems and network
environments. If you're not interested in being a Motif client,
you can still have your application communicate on the desktop
through cut and paste by programming in X or Xt the selection
mechanism using the XA_PRIMARY and XA_CLIPBOARD selections.
If you're interested in learning more about Motif some books to
check are: the OSF /Motif Programmer's Guide, the OSF/Motif
Programmer's Reference, and the OSF/Motif Style Guide. Also, the
"Motif Programming Manual" in the O'Riley Series (Volume 6). For
information on the underlying ICCCM and the X selection mechanism,
the "Inter-Client Communication Conventions Manual; Version 1.0;
MIT X Consortium Standard" by David S. H. Rosenthal is the
official document for ICCCM. Xhibition holds a ICCCM Tutorial
which is very informative. There is also "X Toolkit Intrinsics
Programming Manual" in the O'Riley Series (Volume 4). "X Window
System Toolkit" byPaul J. Asente & Ralph R. Swick is very helpful
for toolkit applications.
=======================================
Application Level Responsibilities: UI
=======================================
You'll need some buttons and probably some pop-up menus when you
implement the user interface. Depending on your application, you
may want at least a CUT, COPY, and PASTE button. CUT and COPY
will have the same behavior at the selection level, but CUT will
alter the application database or display list and thereby remove
the selected object from the screen. You may already have a cut
and paste interface that works within your application. If so,
you're most of the way there.
==================================
Copy or Cut
==================================
Two include files
that you'll need are:
#include <Xm/Xm.h>
#include <Xm/CutPaste.h>
XmClipboardStartCopy()
XmClipboardCopy()
XmClipboardEndCopy()
XmClipboardCopybyName()
When the user chooses the Copy button, the application should
notify Motif that it has some data that it would like to share.
It does this through
XmClipboardStartCopy(Display *display, Window window,
XmString clip_label,
Time timestamp,
Widget widget,
VoidProc callback,
long *item_id);
where the clip_label is the name of the application wishing to
write to the clipboard - most likely built through
XmStringCreate("name", XmSTRING_DEFAULT_CHARSET);
where timestamp is the time of the event that triggered the call -
XtLastTimestampProcessed(display)
...
and then data can be prepared to be posted to the clipboard using
XmClipboardCopy(Display *display,
Window win,
long item_id,
char *format_name,
char *buffer,
unsigned long length,
int private_id,
int *data_id)
for
each of the formats that the application wants to make available.
To notify Motif that the copy to temporary storage is finished
and to do the actual copy from the temporary storage area to
the clipboard, call,
XmClipboardEndCopy(Display *display, Window win, long item_id)
There are times when the amount of data to be posted to the
clipboard is large and once there may never be used. Motif
provides for this circumstance by allowing applications to Copy
by Name rather than posting the actual data thereby saving
resources and improving performance. When a request for the
data occurs, then the application is notified through the callback
provided in XmClipboardCopyStart -and that callback should call:
XmClipboardCopyByName(Display *display,
Window win,
int data_id,
char *buffer,
unsigned long length,
int private_id)
to affect the actual transfer of the data in buffer to the
clipboard so it can be pasted by the requesting application.
==================================
Paste
==================================
XmClipboardStartRetrieve()
XmClipboardRetrieve()
XmClipboardEndRetrieve()
XmClipboardInquireCount()
XmClipboardInquireFormat()
XmClipboardInquireLength()
When an application wants to paste data that is out on the clipboard,
it notifies Motif to begin the retrieval of data by
XmClipboardStartRetrieve(Display *display,
Window win,
Timestamp timestamp)
This routine locks the clipboard until XmClipboardEndRetrieve is called.
Next, the application can begin to make inquiries to see if
the clipboard data is in the format that it needs by using some
of the auxilliary Inquire functions.
XmClipboardInquireCount
returns the number of formats that are available for the next paste
item in the clipboard. It also returns the maximum length of the
format names posted - this is for use in the next routine. The
application can now loop for count times to get the formats that
are available for the next paste item.
XmClipboardInquireFormat
returns the format name for a given index. The application can
check these formats for the most desirable match and then ask how
much data is available by
XmClipboardInquireLength
and begin to retrieve the paste data with
XmClipboard Retrieve( Display *display, Window window,
char *format_name,
char *buffer,
unsigned long length,
unsigned long *num_bytes,
int *private_id)
When the application gets the return value of ClipboardSuccess, it
knows that all of the data has been transferred and so should call
XmClipboardEndRetrieve(Display *display, Window window)
to signal to Motif that the copy is done and to remove the lock
from the clipboard.
There are other auxilliary functions available to the Motif client to
control the clipboard. They are:
XmClipboardCancelCopy
XmClipboardUndoCopy
XmClipboardInquirePendingItems
XmClipboardLock
XmClipboardRegisterFormat
XmClipboardUnlock
XmClipboardWithdrawFormat
Documentation
Reference
Subdirectories
OR, ...